\documentclass[a4paper,10pt]{report}
%\documentclass[a4paper,10pt]{scrartcl}

%\usepackage[utf8]{inputenc}
%\usepackage{ngerman}
%\usepackage[ngerman]{babel}
%\usepackage[DIV10,BCOR2cm]{typearea}
\usepackage{makeidx}
\usepackage{eurosym}
\usepackage{amssymb}
\usepackage{amsfonts}
%\usepackage[pdftex]{color,graphicx}
%\usepackage[pdftex,colorlinks=true,pdftitle={Development of a multitouch sensor for LCD screens},pdfauthor={Thomas Pototschnig},
%            citecolor=black,linkcolor=black,filecolor=black,urlcolor=black]{hyperref}
\usepackage{lscape}
\usepackage{subfigure}
\usepackage{ifthen}
\usepackage{color}
\usepackage{todo}
%\usepackage{timing}
%\usepackage{bibgerm}
%\usepackage{setspace}
\usepackage{amstext}
%\usepackage{sansmath}
\usepackage{listings}
\usepackage{hyperref}
\usepackage{pdfpages}
 
%\usepackage{xcolor}
\lstset{language=C++, 
        basicstyle=\scriptsize \ttfamily,commentstyle=\scriptsize\rmfamily\itshape,
        showstringspaces=false,keywordstyle=\bfseries, stringstyle=\slshape,
        numbers=left, numberstyle=\scriptsize, stepnumber=1, frame=tlrb
}

\lstdefinelanguage{none}{
  identifierstyle=
}

\definecolor{delim}{RGB}{20,105,176}
\definecolor{numb}{RGB}{106, 109, 32}
\definecolor{string}{rgb}{0.64,0.08,0.08}

\lstdefinelanguage{json}{
    numbers=left,
    numberstyle=\small,
    frame=single,
    rulecolor=\color{black},
    showspaces=false,
    showtabs=false,
    breaklines=true,
    postbreak=\raisebox{0ex}[0ex][0ex]{\ensuremath{\color{gray}\hookrightarrow\space}},
    breakatwhitespace=true,
    basicstyle=\ttfamily\small,
    upquote=true,
    morestring=[b]",
    stringstyle=\color{string},
    literate=
     *{0}{{{\color{numb}0}}}{1}
      {1}{{{\color{numb}1}}}{1}
      {2}{{{\color{numb}2}}}{1}
      {3}{{{\color{numb}3}}}{1}
      {4}{{{\color{numb}4}}}{1}
      {5}{{{\color{numb}5}}}{1}
      {6}{{{\color{numb}6}}}{1}
      {7}{{{\color{numb}7}}}{1}
      {8}{{{\color{numb}8}}}{1}
      {9}{{{\color{numb}9}}}{1}
      {\{}{{{\color{delim}{\{}}}}{1}
      {\}}{{{\color{delim}{\}}}}}{1}
      {[}{{{\color{delim}{[}}}}{1}
      {]}{{{\color{delim}{]}}}}{1},
}

\usepackage{wrapfig}
\usepackage{lscape}
\setlength{\parindent}{0pt} % Kein Einr�cken beim Absatz!!
\setlength{\parskip}{3pt}

\usepackage{xcolor}
\usepackage{listings}
\lstset{basicstyle=\ttfamily,
  showstringspaces=false,
  commentstyle=\color{red},
  keywordstyle=\color{blue}
}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\def\xcolorversion{2.00}
\def\xkeyvalversion{1.8}

\usepackage[version=0.96]{pgf}
\usepackage{tikz}
\usetikzlibrary{arrows,shapes,snakes,automata,backgrounds,petri}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\usepackage{ucs}
\usepackage[utf8x]{inputenc}

\usepackage[T1]{fontenc}
%\usepackage[latin1]{inputenc}
%\usepackage{german}

\PrerenderUnicode{ä} 

\renewcommand{\normalsize}{\fontsize{9.5}{12}\selectfont}

\renewcommand{\tt}[1]{\texttt{#1}}

\newcommand{\myfig}[3]{
\begin{figure}[htbp]
\centering\includegraphics[width=#1]{#2}\caption{#3}
\end{figure}
}

\newcommand{\myfigh}[3]{
\begin{figure}[h!]
\centering\includegraphics[width=#1]{#2}\caption{#3}
\end{figure}
}

\newcommand{\myfighl}[4]{
\begin{figure}[h!]
\centering\includegraphics[width=#1]{#2}\caption{#3}\label{#4}
\end{figure}
}

\newcommand{\myfighc}[4]{
\begin{figure}[h!]
\centering\includegraphics[width=#1]{#2}\caption[#4]{#3}
\end{figure}
}

\newcommand{\myfighlc}[5]{
\begin{figure}[h!]
\centering\includegraphics[width=#1]{#2}\caption[#5]{#3}\label{#4}
\end{figure}
}

\def\TReg{\textsuperscript{\textregistered}}
\def\TCop{\textsuperscript{\textcopyright}}
\def\TTra{\textsuperscript{\texttrademark}}

\setlength{\textwidth}{14cm}
\setlength{\textheight}{24cm}
\setlength{\evensidemargin}{10mm}
\setlength{\oddsidemargin}{10mm}
%\setlength{\headwidth}{15cm}
\setlength{\topmargin}{10mm}

\newcommand{\xsf}[2]{\fontsize{#1}{#2}\selectfont}

%\setcounter{secnumdepth}{3}
%\setcounter{tocdepth}{3}

\usepackage{array,booktabs}
\newcolumntype{P}[1]{>{\centering\arraybackslash}p{#1}}


\usepackage{lmodern}
\renewcommand*\familydefault{\sfdefault} %% Only if the base font of the document is to be sans serif
\usepackage[T1]{fontenc}

\title{CryptoCore Manual}
\author{Thomas Pototschnig}
\date{2019-12-04}

\pdfinfo{%
  /Title    ()
  /Author   ()
  /Creator  ()
  /Producer ()
  /Subject  ()
  /Keywords ()
}

\pagestyle{plain}
\pagenumbering{roman}

\usepackage{geometry}
 \geometry{
 a4paper,
 total={170mm,257mm},
 left=20mm,
 top=20mm,
 }
 
\begin{document}
\maketitle
\newpage
This manual is written for engineers and programmers who are involved in the development of products that use the CryptoCore.

\tableofcontents

\chapter{Hardware Overview}
\include{overview}
\newpage
\include{devboard}

\chapter{Quickstart}
\include{raspberry_quickstart}


\chapter{Development Tools}

\include{pc_tools}

\chapter{Cookbook}


\input{cookbook_raspberry}
\input{cookbook_pc}



\include{riscv_debug}
\section{Debugging the RISC-V firmware}

This guide explains how to debug the RISC-V firmware on the ICCFPGA module.

You can use one of the following options to debug the firmware:

\begin{itemize}
\item Use a USB JTAG
\item Use a Raspberry Pi as a debugging server
\end{itemize}

For both options, you need to install Eclipse for RISC-V, which is a popular development environment that we use in this manual to debug the RISC-V firmware. 

You can download Eclipse for free here: \url{https://github.com/gnu-mcu-eclipse/org.eclipse.epp.packages/releases/}

\subsection{Debugging the RISC-V firmware with a USB JTAG} 

You can use any compatible variants of USB JTAG that use the FT2232 chipset.
\textbf{Note:} Variants that have +5V on pin 1 and +3.3V on pin 3  cannot be used on version 1.0 of the development board version 1.0.

Here is an example of a USB JTAG with a compatible pinout:

\begin{center}
 \includegraphics[width=17cm]{img/jtag-riscv.jpg}\label{jtagriscv}%\caption{RISC-V JTAG}
\end{center}
 
\bigbreak

\begin{enumerate}
\item Set jumper J9 to ``CON'' for ``RISC-V'' to enable debugging. In this mode, Eclipse will start the OpenOCD server.
\item Create an OpenOCD debugging profile such as the following:
\begin{center}
 \includegraphics[width=16cm]{img/debug1.png}
\end{center}
\item In the \textbf{Debugger} tab, complete the fields and set the OpenOCD executable path to the location where you installed OpenOCD
\begin{center}
\includegraphics[width=16cm]{img/debug2.png}
\end{center}
\item Complete the ``Startup'' Page
\begin{center}
 \includegraphics[width=16cm]{img/debug3.png}
\end{center}
\item Click \textbf{Apply} >  \textbf{Debug} to start debugging
\end{enumerate}

\clearpage
\subsection{Debugging the RISC-V Firmware with a Raspberry Pi}

The RISC-V `VexRiscv` uses a non-standard debugging interface that needs a particular version of OpenOCD.

To extend this version of OpenOCD with configuration files for the development board, we forked the VexRiscv repository.

\begin{enumerate}
\item Compile our forked version of OpenOCD for RISC-V
\begin{lstlisting}[language=bash,caption={Compiling OpenOCD}]
sudo apt-get install libtool automake libusb-1.0.0-dev texinfo libusb-dev \
    libyaml-dev pkg-config
git clone https://github.com/shufps/openocd_riscv
cd openocd_riscv
./bootstrap
./configure --enable-bcm2835gpio --enable-ftdi --enable-dummy --enable-sysfsgpio
make
sudo make install
\end{lstlisting}
\item On the development board, set jumper J9 to ``PI'' for ``RISC-V''
\item Start an OpenOCD server on the Raspberry Pi. \textbf{Note:} If you are using Raspberry Pi 3, please use `interface/raspberry3-native-iccfpga-vexrisc.cfg`.
\begin{lstlisting}[language=bash,caption={Starting OpenOCD on Raspberry Pi}]
sudo openocd -c "bindto 0.0.0.0" \
    -f interface/raspberry4-native-iccfpga-vexriscv.cfg \
    -f target/iccfpga-vexriscv.cfg
\end{lstlisting}
\item Connect to the OpenOCD server from Eclipse. \textbf{Note:} Make sure the firewall does not block port 3333, and enter the IP address of your Raspberry Pi in the Remote-Target section.
\begin{center}
 \includegraphics[width=15cm]{img/debug4.png}
\end{center}
\item Click \textbf{Apply} > \textbf{Debug} to start debugging
\end{enumerate}

\bigskip

\subsection{Uploading RISC-V Firmware to the ICCFPGA module, using OpenOCD on a Raspberry Pi}

To upload RISC-V firmware to the ICCFPGA module without using Eclipse, you can use the OpenOCD server on the Raspberry Pi.

\begin{enumerate}
\item Upload the code through OpenOCD. \textbf{Note:} If you're using a Raspberry Pi 3, replace `interface/raspberry4-native-iccfpga-vexriscv.cfg` with `interface/raspberry3-native-iccfpga-vexriscv.cfg`.
\begin{lstlisting}[language=bash,caption={Upload Code to RISC-V with OpenOCD}]
sudo openocd -f interface/raspberry4-native-iccfpga-vexriscv.cfg \
    -f target/iccfpga-vexriscv.cfg -c "init" -c "reset halt" \
    -c "load_image iccfpga-rv.elf 0x00000000" -c "reset run" \
    -c "resume" -c "exit"
\end{lstlisting}
\item Take the ICCFPGA module out of reset state
\begin{lstlisting}[language=bash,caption={Unreset RISC-V}]
#!/bin/bash
# export jtag_rv_reset, switch pin to output and deassert reset

cd /sys/class/gpio
echo 19 > export
echo "out" > gpio19/direction
echo "1" > gpio19/value
\end{lstlisting}
\end{enumerate}

\newpage
\section{Securing the FPGA}

For debugging purposes, you can upload firmware to the ROM in the RISC-V soft CPU through the RISC-V JTAG.

For production applications, this JTAG interface is insecure because it allows others to access the firmware.

Therefore, when you finish developing your application, you can complete the following steps to secure the system.

\begin{enumerate}
 \item Lock the JTAG
 \item Change the API key
 \item Change the secret key
 \item Enable bitstream encryption
\end{enumerate}

\subsection{Locking the JTAG}

Locking the JTAG stops others from accessing the ROM in your RISC-V soft CPU.

\begin{enumerate}
\item In the Vivado Block Design, set the variable `Lock` of the component `jtag\_0` to `1`
\begin{center}
\includegraphics[width=15cm]{img/jtaglock.png}
\end{center}
\item Synthesize the system to remove the JTAG interface from the hardware.
\end{enumerate}

Firmware can no longer can be uploaded through the RISC-V JTAG. Instead, it must be embedded in the bitstream.

\textbf{Tip:} The Lock flag can be read by the CPU by reading GPIO pins 31.

\subsection{Changing the API Key}

The API key is used to authenticate calls to API commands that read the seed from the secure element. Because UART communication is not encrypted, the API key ensures that data hasn't been modified on the way to the ICCFPGA module.

Currently, the API key is stored in the `iccfpga-rv/secure/secure.cpp` file:

\begin{lstlisting}[language=c,caption={API Key}]
const uint8_t g_api_key[48] = { 
    0xb2, 0x33, 0x12, 0x56, 0x41, 0xf0, 0xcc, 0x60, 0x9c, 0x6f, 0x36, 0x30, 0xe7, 
    0xf3, 0xb2, 0xfd, 0xb7, 0x2b, 0xbd, 0x2e, 0x94, 0x40, 0xa5, 0xb0, 0x0a, 0xb5,
    0x83, 0x65, 0x5b, 0x01, 0xb1, 0x43, 0xdf, 0x31, 0x3e, 0x9a, 0xa0, 0x90, 0x72, 
    0x02, 0xdf, 0x5f, 0x16, 0x40, 0x8e, 0x64, 0xf4, 0xd4
};
\end{lstlisting}

If you change this key, you must recompile the RISC-V firmware.

\subsection{Changing the Secret Key}

The secret key is used to encrypt and decrypt data sent between the RISC-V firmware and the secure element.

Currently, the secret key is stored in the `iccfpga-rv/secure/secure.cpp` file:

\begin{lstlisting}[language=c,caption={AES Key}]
// this has to be changed by the user to ensure security
const uint8_t g_slot4_key[32] = { 
    0x37, 0x80, 0xe6, 0x3d, 0x49, 0x68, 0xad, 0xe5, 0xd8, 0x22, 0xc0, 0x13, 0xfc, 
    0xc3, 0x23, 0x84, 0x5d, 0x1b, 0x56, 0x9f, 0xe7, 0x05, 0xb6, 0x00, 0x06, 0xfe, 
    0xec, 0x14, 0x5a, 0x0d, 0xb1, 0xe3 
};
\end{lstlisting}

If you change the secret key, you must use the API to initialize the secure element to set the new secret key. See \ref{apiInit}.

\clearpage

\subsection{Enabling Bitstream Encryption}

To stop others from being able to read your bitstream, you can encrypt it before uploading or flashing it to the ICCFPGA module.

\begin{enumerate}
\item Clone the `iccfpga` repository. The key for bitstream encryption is in the `iccfpga-core/iccfpga/iccfpga.xdc` file.
\begin{lstlisting}[language=bash,caption={Cloning the Repositories}]
git clone --recursive https://gitlab.com/iccfpga-rv/iccfpga
cd iccfpga/iccfpga-eclipse/submodule/ArduinoJson
git checkout 5.x
\end{lstlisting}
\item In the constraints file, comment out either the `BRAM` or `eFUSE` line, depending on how you want to store the AES keys (BRAM is volatile memory, and eFUSE is non-volatile memory). The AES key is a 64 digit hexadecimal string.
\begin{lstlisting}[language=bash,caption={Constraints File}]
#encryption settings
set_property BITSTREAM.ENCRYPTION.ENCRYPT YES [current_design]
set_property BITSTREAM.ENCRYPTION.ENCRYPTKEYSELECT BBRAM [current_design]
#set_property BITSTREAM.ENCRYPTION.ENCRYPTKEYSELECT eFUSE [current_design]
set_property BITSTREAM.ENCRYPTION.KEY0 256'h7821461...2382B4D [current_design]
\end{lstlisting}
\item In Vivado, generate the encrypted bitstream
\end{enumerate}

If encryption is enabled in the constraints file, you should now have an NKY file

\begin{lstlisting}[language=bash,caption={NKY Example File}]
iccfpga/iccfpga.runs/impl_1$ cat design_iccfpga_wrapper.nky 
Device xc7s50;
Key 0 78214125442A472D4B614E645267556B58703273357638792F423F4528482B4D;
Key StartCBC 8b4bd4762870cf71061cce9ef1401f07;
Key HMAC 25fd439344cfccf18562bc9f67301b1559186382f82af6a6d207db8aa5ba4b62;
\end{lstlisting}

Now, you can program your encryption key into memory, using one of the following options:

\begin{itemize}
\item Volatile BBRAM memory (useful for testing encryption)
\item Non-volatile eFUSE memory (useful for production environments)
\end{itemize}

\subsubsection{Programming the FPGA keys to BBRAM (volatile)}

\begin{enumerate}
\item In Vivado, click \textbf{Program BBR Key}
\begin{center}
\includegraphics[width=16cm]{img/bbr.png}
\end{center}
\end{enumerate}

After programming the BBRAM file, you can upload the encrypted bitstream to the ICCFPGA.

Please note that the BBRAM is volatile and there is no backup battery on the ICCFPGA module.

To store the encrypted bitstream in the flash memory on the module, the key has to be programmed to eFUSE.

\subsubsection{Programming the FPGA keys to eFUSE (permanent)}

\textbf{Note:}  This option is permanent and if you lose the key, you won't be able to recover the ICCFPGA.

\begin{enumerate}
\item In Vivado, click \textbf{Program eFUSE registers}
\begin{center}
\includegraphics[width=16cm]{img/aes1.png}
\end{center}
\item Select the NKY file and click \textbf{Next}
\item Complete the fields, using the following recommended values. \textbf{IMPORTANT:} \label{aesenable} Don't select the first option unless you know what you are doing. After setting CFG\_AES\_ONLY, it will no longer be possible to program the QSPI flash memory via the Vivado hardware manager. This is a known problem without solution: \url{https://www.xilinx.com/support/answers/44116.html}.
\begin{center}
\includegraphics[width=16cm]{img/aes2.png}
\end{center}
\end{enumerate}

Now, only the RISC-V firmware has access to the QSPI flash memory and is able to write updated bitstreams to the flash.

\section{Compiling the RISC-V Firmware}



\section{Embedding RISC-V firmware in the bitstream}

TODO

\textbf{Note:} ROM can be embedded (in the fast way) only if encryption is disabled. If bitstream encryption is enabled, the ROM code has to be synthesized together with the FPGA system. Encrypting bitstreams after replacing the ROM is not possible (perhaps it is possible but currently unknown how it works - probably via some TCL-magic in Vivado).

\newpage

\include{api}
\newpage
\chapter{Appendix}




\include{programmers_manual}
\newpage
\section{SoC System Overview}
%\vspace{-1.4cm}
\hspace{-1cm}\includegraphics[width=20cm]{img/design_iccfpga.pdf}

\clearpage 
\section{ICCFPGA Module Component Placement and Schematic} 
\begin{center}
\includegraphics[scale=4.5]{img/iccfpga-F_Fab.pdf}
\end{center}
\begin{center}
\includegraphics[scale=4.5]{img/iccfpga-B_Fab.pdf}
\end{center}
\clearpage
\includepdf[landscape=true, fitpaper=true]{img/iccfpga-module.pdf}
 
\clearpage
\section{Development Board Component Placement and Schematics}
\vspace{1cm}
\begin{center}
\includegraphics[scale=2.5,angle=90,origin=c]{img/iccfpga-dev-F_Fab.pdf}
\end{center}
\includepdf[landscape=true, pages=2, fitpaper]{img/iccfpga-dev.pdf}
\includepdf[landscape=true, pages=3, fitpaper]{img/iccfpga-dev.pdf}
\includepdf[landscape=true, pages={4-5}, fitpaper]{img/iccfpga-dev.pdf}

\end{document}
